Other Adapters and Platform Access Options

This chapter explains other Adapters which are not only responsible for accessing a defined type of resource. The following adapters allow for data exchange with the Expeditor integrator runtime without using the messaging channel.

REST Adapter

Overview

The REST (REpresentational State Transfer) Adapter provides data access to the Expeditor integrator runtime through HTTP. In addition to the messaging channel access, the REST Adapter allows for exchanging message content with Expeditor integrator, but uses HTTP. This is important for the integration of other not-messaging-based legacy systems (e.g. terminals, PDAs).

Figure 9 shows the REST Adapter architecture. The HTTP Request is taken and transformed into an Expeditor integrator compliant message. This message is then placed into the ReqInQ or CtrlQ in the same way as the messaging system would do it. From there on, the previous HTTP request is handled in the same way as any incoming message. The process of the HTTP request message is tracked in the Persistence Service. This information is taken to provide an appropriate response to the initial HTTP Request.

Figure 9: REST Adapter Architecture Overview

Please, refer to Using the IBM Expeditor integrator platform for details about how the REST Adapter can be used for data exchange with Expeditor integrator.

REST Adapter Configuration

The configuration relevant parameters can be found in Listing 21. There, the Expeditor integrator standard configuration is given:

• for the routing of the possible HTTP Request messages to the correct inbound queues,
• for the mapping of the HTTP-Request-Header to the Expeditor integrator JMS Custom Header properties.

Note: The user name and password required for accessing the Web Container of Expeditor integrator is managed by the User Admin Service and is configured separately. The initial configuration is provided in the XPDintegDefaultRoles.xml file. This can be changed using the available Expeditor integrator configuration update mechanisms. Please, refer to section ‎8 for more details.

Listing 21: REST Adapter configuration example


The following Table 21 explains the possible parameters for the REST adapter.

Table 21: REST adapter parameters

Property	Explanation
connectionFactory	JNDI key for the Microbroker. E.g.: jms/XPDinteg_ConnectionFactory need to map to the microbroker definition in the messaging section
routing.messagepurpose.	JNDI key of the destination corresponding to the MessagePurpose. E.g.: FileTransfer requests are forwarded to the queue with the JNDI name "jms/XPDinteg_ReqInQ”
header-mapping.	This section contains the mapping between the HTTP header an the Expeditor integrator message headers E.g.: the HTTP header “ibmxpdintegrator-messagepurpose is mapped to the MessageHeader “MessagePurpose”

The Webcontainer can not be configured using the XPDinteg.xml. Parameters of interest are the HTTP and HTTPS port and the HTTP address setting.

Please find in Table 22 the detailed description about the Web Container parameters and its defaults.

Table 22: IBM Lotus Expeditor Client WebContainer parameters for Expeditor integrator

Property	Explanation
HTTP Port	Defines the port used by the HTTP Service listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests. This property now supports a list of values. Default: 8777
HTTPS Port	Defines the port used by the HTTPS Service listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests. This property now supports a list of values. Default: 9001
HTTP Address	Defines the host address for the default ports that the Web Container listens on. If this property is defined then the Web Container will only listen for requests that come through this IP address. The special value ALL indicates all available IP addresses on the computer will be used. The value of this property may be a resolved name or IP address (for example, www.ibm.com, 192.168.0.101, localhost). Default: ALL

To change these parameters after the Expeditor integrator was deployed, the following file steps need to be done:

• find the file \rcp\eclipse\plugins\com.ibm.rcp.base_\config\pbuilder\rcpinstall.properties
• Update the HTTP port parameter: -Dcom.ibm.pvc.webcontainer.port=yournewport
• Update the HTTPS portparameter: -Dcom.ibm.pvc.webcontainer.port.secure=yournewport
• Update the HTTP adress parameter: -Dcom.ibm.pvc.webcontainer.http.address=newadress
• Restart the Expeditor integrator.

The file retrieval and send file tasks can be achieved remotely by using the Expeditor integrator capabilities.

Please, refer to APPENDIX B – Technical Details for steps to enable the IBM Lotus Expeditor Client WebContainer access through SSL.

Graphical User Interface Access Configuration

IBM Lotus Expeditor integrator provides a framework for a browser-based graphical user interface. This JavaScript based framework provides common look and feel. It consists of the Expeditor integrator Start Page which displayes a status overview and additional pages which can be dynamically plugged in as user interfaces for custom applications.

Per default, it provides access to administrative functions, for example:

• Administrators page for installation, un-installation, start / stop of components and of the complete runtime
• Monitor page for displaying current and historical status information of ACS Flows and Adapters.
• Configuration page for retrieving, editing and deploying the configuration of Expeditor integrator runtimes (e.g. helps to create the XPDinteg.xml config file)
• Test page which can be used to run test cases on selected Expeditor integrator runtimes and MQ-based back-ends.

Per default, the GUI can be accessed under: http://xpdinteghost:8777/ui/home
(Please, refer to Expeditor integrator Graphical User Interface for more Expeditor integrator GUI details.)

General format:


Table 23 provides an explanation of the available properties.

Table 23: GUI configuration properties

Property	Explanation
	Property tag for the configuration section of one GUI page. name is the name of the installed plug-in (Servlet) which provides the GUI functions for this page. e.g.
	Enables / disables this application’s page in the common Expeditor integrator GUI. values: TRUE or FALSE
	List of user access roles for which this application’s page is displayed. These roles must match the authenticated user’s roles in the Expeditor User Admin Service. Note: This setting does not prevent directly accessing the URI of this application. It just does not display this application in the common Expeditor integrator GUI.

The users and roles are managed by the User Admin Service which can also be configured by Expeditor integrator (see Expeditor integrator Access Control). The default users and roles are loaded from the /config/system/XPDintegDefaultRoles.xml file. Changes to these roles can either be applied by the Expeditor Client Manager (server) or through Expeditor integrator ConfigUpdate messages (see Expeditor integrator Access Control).

An example is provided in Listing 22.

Listing 22: Expeditor integrator GUI configuration example (integrates the default Admin and Config GUI pages)

The Expeditor integrator GUI provides the Configuration Page. This can be used to create a custom XPDinteg.xml configuration file and to edit all the possible configuration options mentioned earlier.

Please, refer to Using the IBM Expeditor integrator platform (‎Ref_2) for more details about using the Expeditor integrator GUI.

Note: Per default, only a locally running browser can access the Expeditor integrator GUI. Remote access by other computers can be enabled by configuring the /config/system/ssl/vconfig.txt file.  To allow remote access to the GUI, add the client's IP address and the port to the GUI's virtual host:

Wildcards may be used for the virtual host, IP address, and port to broaden access. Additionally, ensure that Interim Fix 1 is applied to the Integrator for proper function.

Expeditor integrator Resource Mapper Configuration

The Expeditor integrator Resource Mapper provides the opportunity to configure parameters which are required for transferring files and other resources from Expeditor integrator (outbound) and to Expeditor integrator (inbound) in a common place for a group of resources. Resource groups with common properties are classified through the ResourceType property. The ResourceType is an Expeditor integrator JMS Custom Header property through which different data messages can be identified (see Using the IBM Expeditor integrator platform ‎Ref_2 for more details).

Detailed configuration parameters which apply to a given Resource Type can be grouped in the Resource Mapper in order to make the Expeditor integrator configuration more readable. There are default Resource Types, but custom Resource Types can also be introduced to group resources and their configuration.

Inbound Resource Mapper

If the ResourceType property is used for incoming messages (inbound), the Resource Mapper can hold configuration values which are applied to the received resource (e.g. ResourceType=SampleFtpFile, then all resource properties could be stored in the Resource Mapper rather then providing them again and again in each incoming message with the same file as payload). This means that the Resource Mapper is used as configuration store for additional JMS Custom Header properties which are added to an incoming/triggering JMS message. Therefore, the Resource Mapper configuration properties are processed in the same way as the original JMS custom message header properties (e.g. they have higher priority than the ACS Activity configuration in the XPDinteg.xml and in the ACS flow definition files). The mapping key is the ResourceType.

General Format:


Basically, all properties which are available for the Expeditor integrator Resource Adapters can be used in the Resource Mapper configuration (refer to chapter ‎4.4 for the Resource Adapter configuration options). Table 24 shows the configuration options for the Inbound Resource Mapper.

Table 24: Inbound Resource Mapper configuration options

Property	Explanation
<inbound-mappings>	Resource Mapper direction: inbound for resource transmission back-end -> Expeditor integrator outbound for resource transmission Expeditor integrator -> back-end
	"SampleFtpFile" Maps to JMS Custom Header property ResourceType (see Using the IBM Expeditor integrator platform; ‎Ref_2). This unique ID is used to assign resource adapter settings to settings in the Resource Mapper
	Different transport types that identify the Resource Adapter which is used. Possible values: "FTP" – for FTP Adapter, "LocalFileSystem" – for Local File System Adapter, "SSH" – for SSH File Adapter, "DB" – for Database Adapter
	String: description of the resource mapping
"ASCII" or "BINARY" "ASCII" – (file) transfer mode is ASCII (e.g. for FTP access) "BINARY" – (file) transfer mode is binary (e.g. for FTP access)
	Defines write operation in case the resource already exists. "APPEND" – append new (file) resource to existing one "OVERWRITE" – overwrite with new (file) resource
	String which contains target path to which the received resource transferred (e.g. file directory – forward slashes only) Note: Must not be empty (use value="/"/> instead)
	String which contains the name of the destination resource (e.g. file name). This value can be provided dynamically (e.g. value="&lt;TRANSID_8&gt;.TXT" would create a file name out of the last 8 digits of the transaction ID with the file extension .TXT, see Using the IBM Expeditor integrator platform for more options; ‎Ref_2).
	“UTF-8” or “UTF-16” etc. Type of data encoding.
	String with hostname or IP address of FTP target server in case of FTP file transfer
	String with port number of FTP target server in case of FTP file transfer (default: value="21")
	Indicates whether passive or active transfer mode is used for FTP file transfer. Possible values: "TRUE" or "FALSE"
	"ftp_user" – contains the name of the FTP target server user account
	"ftp_passwd" – contains the password for the FTP target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter ý4.12)
	Defines the type of the FTP target server "DEFAULT" – for standard OS FTP servers (Linux, Unix and Windows) "4690" – for FTP server on 4690 PoS controllers
	String with hostname or IP address of SSH target server in case of SSH based file transfer
	String with port number of SSH target server in case of SSH based file transfer (default: value="22")
value=	"ssh_user" – contains the name of the SSH target server user account
	"ssh_passwd" – contains the password for the SSH target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter ý4.12)
	SSH server type: “SFTP” or “SCP”

Configuration examples for Local File System Adapter Resource Mapping are given in section ‎3 (Listing 3) and in the included XPDinteg.xml file.

Outbound Resource Mapper

The ResourceType property can also be used during Resource Adapter configuration (see chapter ‎4.4) to assign resource access configuration properties to a group of Adapters or a single Adapter and to outgoing data messages (outbound). For example, if the a FTP Resource Adapter is configured with



(ResourceType=SampleFtpFile), all further configuration values do not need to be placed in the Adapter’s section. These configuration values could also be stored in the outbound Resource Mapper so that it is usable by other Adapters and Resources as well.

General Format:

 <resources> 

<outbound-mappings>

<resource-mapping type="SampleFtpFile">

<param name="TransportType" value="FTP"/>

<param name="Description" value="Sample FTP file"/>

<param name="TransferMode" value="ASCII"/>

<param name="TransferConfirmationMode" value="WriteOtherFile"/>

<param name="WriteOtherFileName" value="sample.trf"/>

<param name="Encoding" value="UTF-8"/>

<param name="FtpServer" value="ftp_server_name"/>

<param name="FtpServerPort" value="21"/>

<param name="FtpPassive" value="TRUE"/>

<param name="FtpUser" value="ftp_user"/>

<param name="FtpPassword" value="ftp_passwd"/>

<param name="FtpType" value="DEFAULT"/>

<param name="TransferPriority" value="9"/> 

Many configuration values for the Outbound Resource Mapper are the same as the ones for the Inbound Resource Mapper and are also available for the Resource Monitor Adapter configuration. Refer to Table 25 for an overview of the configuration options.

Table 25: Outbound Resource Mapper configuration options

Property	Explanation
<outbound-mappings>	Resource Mapper direction: outbound for resource transmission Expeditor integrator -> back-end inbound for resource transmission back-end -> Expeditor integrator
	"SampleFtpFile" Maps to JMS Custom Header property ResourceType (see Using the IBM Expeditor integrator platform; ‎Ref_2). This unique ID is used to assign resource adapter settings to settings in the Resource Mapper.
	Different transport types that identify the Resource Adapter which is used. Possible values: "FTP" – for FTP Adapter, "LocalFileSystem" – for Local File System Adapter, "SSH" – for SSH File Adapter, "DB" – for Database Adapter
	String: description of the resource mapping
"ASCII" or "BINARY" "ASCII" – (file) transfer mode is ASCII (e.g. for FTP access) "BINARY" – (file) transfer mode is binary (e.g. for FTP access)
	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. "NONE" – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) "DELETE" – delete the file resource(s) in the source directory "RecreateZero" – recreate a file with length zero byte, but with the same name as the source file resource "WriteOtherFile" – source file is re-named with the name provided in WriteOtherFileName
"WriteOtherFileName" value=	"sample.trf" String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile)
	“UTF-8” or “UTF-16” etc. Type of data encoding.
	String with hostname or IP address of FTP target server in case of FTP file transfer
	String with port number of FTP target server in case of FTP file transfer (default: value="21")
	Indicates whether passive or active transfer mode is used for FTP file transfer. Possible values: "TRUE" or "FALSE"
	"ftp_user" – contains the name of the FTP target server user account
	"ftp_passwd" – contains the password for the FTP target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter ý4.12)
	Defines the type of the FTP target server "DEFAULT" – for standard OS FTP servers (Linux, Unix and Windows) "4690" – for FTP server on 4690 PoS controllers
	String with hostname or IP address of SSH target server in case of SSH based file transfer
	String with port number of SSH target server in case of SSH based file transfer (default: value="22")
value=	"ssh_user" – contains the name of the SSH target server user account
	"ssh_passwd" – contains the password for the SSH target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter ý4.12)
	SSH server type: “SFTP” or “SCP”

Configuration examples for Local File System Adapter Resource Mapping are given in section ‎3 (Listing 2) and in the included XPDinteg.xml file.

Default Resource Mapper Configurations

Standard Expeditor integrator Resource Mappers

The following Listing 23 shows the standard Resource Mappers which are required for Expeditor integrators operation.

Listing 23: Standard Expeditor integrator Resource Mapper configuration (for ConfigUpdate and ScriptFile control messages)

 <inbound-mappings> 

<resource-mapping type="ConfigurationUpdateFile"> 

<param name="TransportType" value="LocalFileSystem"/>

<param name="Description" value="Properties File"/>

<param name="TransferMode" value="ASCII"/>

<param name="DestinationCreationMode" value="OVERWRITE"/>

<param name="DestinationPath" value="config"/>

<param name="DestinationName" value="XPDinteg.xml"/>

<param name="Encoding" value="UTF-8"/> 

</resource-mapping>

<resource-mapping type="ScriptFile"> 

<param name="TransportType" value="LocalFileSystem"/>

<param name="Description" value="Script File"/>

<param name="TransferMode" value="ASCII"/>

<param name="DestinationCreationMode" value="OVERWRITE"/>

<param name="DestinationPath" value="config"/>

<param name="DestinationName" value="script.bat"/>

<param name="Encoding" value="UTF-8"/>

</resource-mapping>

</inbound-mappings> 

Example Resource Mappers for Retail Customers

Example file transfer configurations for the Resource Mapper are given in sample files in the /samples/config directory (also, see chapter ‎3.2.2).
Mappings for the following file types are provided:

• Inbound
  • PriceUpdFile
  • MappingDataFile
  • DiscountDataFile
  • ScaleDataFile
  • PrintLabelFile
  • ShelfLabelFile
• Outbound
  • PosTransDataFile1
  • PosTransDataFile2
  • OtherTransDataFile
  • PosProdDataFile
  • TlogFile
  • CreditNotesFile
  • PaybackDataFile
  • PressDataFile
  • EventsFile

An example configuration file XPDinteg.xml can also be found in the /samples/config folder.

Application Control Service Configuration

Configuration of Application Use Cases

Since the Expeditor integrator is purely messaging and event driven, the behavior can be configured from the use case perspective by configuring the Expeditor integrator Application Control Service (ACS) flows. Expeditor integrator system flows are stored in \flowdefs\system and should not be changed otherwise the correct operation can not be guaranteed. Expeditor integrator default flow definition files are located in the /flowdefs/default folder (e.g. for file transmission, database record updates). Custom developed flows should be placed into the Expeditor integrator flow root folder /flowdefs. Example ACS Flow definition files can be found under /samples/flowdefs folder.

Each ACS flow consists of a sequence of Activities that perform defined tasks (see Figure 10). Each flow is started by a configurable OSGi Event Admin trigger event.
The Expeditor integrator is delivered with a default set of Activities that can be re-configured and newly chained together to fulfill new business use cases.

Figure 10: Expeditor integrator Resource Adapters monitor resources and notify the Resource Monitor Service in case of changes. Then, the Resource Monitor Service and the Dispatcher Service publish defined flow trigger events using the OSGi Event Admin Service to which ACS Flows have subscribed to. If the flow trigger event matches a given flow, the flow is executed.

Please, refer for further details to the Using the IBM Expeditor integrator platform.

General ACS Configuration

The Expeditor integrator Application Control Service also provides configuration options in Section_9 the XPDinteg.xml file.

General format:

<application-control-service>

<definition-settings>

<directory>directory_for_flowdef_files</directory>

<poll-interval>flow_def_directory_polling_intervall_in_msec</poll-interval>

<extension>flow_config_files_extension </extension>

<retryInterval>read_retry_intervall_in_msec</retryInterval>

</definition-settings>

<permissions>

<multiple-flows-per-topic>false</multiple-flows-per-topic> 

</permissions> 

Table 26: Application Control Service configuration

Property	Explanation
	Tag indicating the ACS configuration section
	directory_for_flowdef_files String which contains the local directory in which the ACS flow definition files are stored (default: /flowdefs)
	flow_def_directory_polling_intervall_in_msec polling interval for the flow definition file changes in msec (default: 60’000ms = 1min)
	flow_config_files_extension standard file extension which indicates a flow definition file (default = .flow)
	read_retry_intervall_in_msec retry interval in msec after which reading of updated ACS flow files is tried (in case it failed before)
	true OR false defines whether one trigger event could kick-off more then one flow (default = false; recommended). One trigger event could start multiple flows. This becomes complex quickly and is therefore only recommended for experienced users.

An example is given in Listing 24.

Listing 24: General ACS configuration example

 <application-control-service>

<definition-settings>

<directory>flowdefs</directory>

<poll-interval>120000</poll-interval>

<extension>flow</extension>

<retryInterval>30000</retryInterval>

</definition-settings>

<permissions>

<multiple-flows-per-topic>false</multiple-flows-per-topic> 

</permissions> 

ACS Activity Configuration

The Using the IBM Expeditor integrator platform contains the list of all available Expeditor integrator Application Control Service Activities (see ‎Ref_2). Some Activities can be independently configured in the flow definition. This allows for different handling of resources for different messages and flows.

The following configuration priority is defined for cases where the JMS Custom Header property, the ACS Activity configuration and the configuration in Section_9 of the XPDinteg.xml are provided:

1. The JMS Custom Header properties and the optionally assigned properties in the Resource Mapper configuration have always highest priority. They overwrite the XPDinteg.xml and the ACS Activity/Flow settings.
2. If JMS Custom Header property is not set, the definitions in the ACS Activity/Flow settings are taken.
3. Lowest priority has the configuration stored in XPDinteg.xml. These settings are always overruled by the JMS Custom Header properties and the ACS Activity/Flow settings.

Table 27 shows a selection of possible configuration options for the most important Activities. Basically, message related Activities can re-use the JMS Message Header properties. The File/SSH/LocalFileSystem related Activities can also re-use the properties of the Resource Adapters.

Listing 25 shows the default configuration of Expeditor integrator for these ACS Activities which can be adjusted to customer specific needs.

Table 27: ACS Activity configuration

Property	Explanation
< activity-configurations >	Tag indicating the ACS Activity configuration section
	Name of the Expeditor integrator activity (see Activity catalogue in Using the IBM Expeditor integrator platform)
"resource_adapter_property" value="my_value"/>	List of pairs which contain configuration options for each activity (see params in Resource Adapter configuration. If these parameters are provided in JMS Custom Header and Resource Mapper properties of an involved message, then the message’s properties have higher priority and will be used. If these parameters are not set here, configuration values from the XPDinteg.xml file will be taken instead.
value=	FTP Resource Adapter specific configuration values (see chapter ý4.4) For Activities: XPDINTEG_BROWSE_FTP_DIRECTORY, XPDINTEG_FILE_READ_FTP, XPDINTEG_FILE_WRITE_TO_FTP XPDINTEG_FILE_TRANSFER_CONFIRMATION
	SSH Resource Adapter specific configuration values (see chapter ý4.4) For Activities: XPDINTEG_BROWSE_SSH_DIRECTORY, XPDINTEG_FILE_READ_SSH, XPDINTEG_FILE_WRITE_TO_SSH XPDINTEG_FILE_TRANSFER_CONFIRMATION
"RetryAttempts" value="200"/>	RetryAttempts – no. of retry cycles in case the remote server is temporary not available RetryInterval – time interval after which the Adapter is polled again For Activities: XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM, XPDINTEG_FILE_WRITE_TO_FTP, XPDINTEG_FILE_WRITE_TO_SSH, XPDINTEG_FILE_TRANSFER_CONFIRMATION
	header version it should be build.		"DISCARD" or "REMOVE" Configuration for cases where any setting in the involved JMS message is wrong (wrong header or payload) InvalidMessageFailureAction value= "DISCARD" – deletes wrong message "REMOVE" – moves wrong message to queue configured under For Activities: XPDINTEG_MESSAGE_TO_FILE, XPDINTEG_MESSAGE_READ
"DISCARD" or "REMOVE" or "PUT_BACK" "DISCARD" – deletes wrong message "REMOVE" – moves wrong message to queue configured under "PUT_BACK" – puts message which can not be processed to original InQ (no of retries was exceeded); Note: This could cause infinite looping of un-processable messages. For Activities: all
	e.g. "jms/XPDinteg_ServerDeadletterQ" JNDI name of the destination queue regarding to value= "REMOVE" of InvalidMessageFailureAction or RollbackMessageAction
"script-execution" value=	"true" OR "false" – configures whether Script execution is allowed or not. For Activity: XPDINTEG_FILE_EXECUTE
"HouseKeeping_specific_params" value=	For Activity: HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY
"ISACollector_specific_params" value=	For Activity: XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY

Listing 25: Application Control Activity Confguration

 <application-control-service>

<activity-configurations>

<configuration activity="XPDINTEG_BROWSE_FTP_DIRECTORY"> 

<param name="ftp_related_parameters!"/>

</configuration>

<configuration activity="XPDINTEG_BROWSE_SSH_DIRECTORY"> 

<param name="ssh_related_parameters!“/>

</configuration>

<configuration activity="XPDINTEG_FILE_READ_FTP">

<param name="ftp_related_parameters!"/>

</configuration>

<configuration activity="XPDINTEG_FILE_READ_SSH">

<param name="ssh_related_parameters!“/>

</configuration>

<configuration activity="XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM">

<param name="RetryAttempts" value="200"/>

<param name="RetryInterval" value="5000"/>

</configuration>

<configuration activity="XPDINTEG_FILE_WRITE_TO_FTP">

<param name="ftp_resource_adapter_related_params“ .../>

</configuration>

<configuration activity="XPDINTEG_FILE_WRITE_TO_SSH">

<param name="ssj_resource_adapter_related_params“ .../>

</configuration>

<configuration activity="XPDINTEG_MESSAGE_TO_FILE">

<param name="Encoding" value="UTF-8"/>

<param name="InvalidMessageFailureAction" value="DISCARD"/>

<param name="RollbackMessageAction" value="PUT_BACK"/> 

<param name="RemoveTargetJNDI" value="jms/XPDinteg_ServerDeadletterQ"/> 

</configuration>

<configuration activity="XPDINTEG_MESSAGE_READ">

<param name="InvalidMessageFailureAction" value="DISCARD"/>

<param name="RollbackMessageAction" value="PUT_BACK"/> 

<param name="RemoveTargetJNDI" value="jms/XPDinteg_ServerDeadletterQ"/> 

</configuration>

<configuration activity="XPDINTEG_FILE_TO_MESSAGE_WRITE">

<param name="MessageSegmentSize" value="2000"/>

<param name="Encoding" value="UTF-8"/>

<param name="CreateHeaderVersion" value="2.0"/>

</configuration>

<configuration activity="XPDINTEG_MESSAGE_WRITE"> 

<param name="CreateHeaderVersion" value="2.0"/>

</configuration>

<configuration activity="XPDINTEG_VALIDATE_TRANSFORM_ACTIVITY">

<param name="XSDLocation" value="config\system\XPDinteg.xsd"/>

<param name="XSLTLocation" value="config\system\XPDinteg.xsl"/>

<param name="OutputXMLLocation" value="config\system\XPDintegConfig.xml"/> 

</configuration> 

<configuration activity="XPDINTEG_FILE_EXECUTE">

<param name="script-execution" value="true"/> 

</configuration>

<configuration activity="XPDINTEG_FILE_TRANSFER_CONFIRMATION"> 

<param name="FtpServer" value="localhost"/>

<param name="FtpServerPort" value="21"/>

<param name="FtpPassive" value="TRUE"/>

<param name="FtpUser" value="test"/>

<param name="FtpPassword" value="test"/>

<param name="FtpType" value="4690"/>

<param name="SshServer" value="ssh_server_name"/>

<param name="SshServerPort" value="22"/>

<param name="SshUser" value="ssh_user"/>

<param name="SshPassword" value="ssh_passwd"/>

<param name="SshType" value="SFTP"/> 

<param name="RetryAttempts" value="200"/>

<param name="RetryInterval" value="5000"/>

</configuration>

6.7 -->

<configuration activity="HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY"> 

<param name="RAM" value="Threshold:256000;Action:REPORT_WARNING"/>

<param name="DiskSpace" value="Threshold:1000000;Action:REPORT_WARNING"/>

<param name="Files" value="Threshold:1000;Action:REPORT_WARNING"/>

</configuration>

<configuration activity="XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY"> 

<param name="FileList1" value="config/XPDinteg.xml"/>

<param name="FileList2" value="config/system/XPDintegConfig.xml"/>

<param name="FileList3" value="config/system/XPDinteg.xsd"/>

<param name="FileList4" value="config/system/XPDinteg.xsl"/>

<param name="IncludeOutput" value="true"/>

<param name="OutputFileThreashold" value="1000"/>

<param name="TransportType" value="BINARY"/>

<param name="Encoding" value="UTF-8"/>

<param name="TransferPriority" value="5"/>

</configuration> 

</activity-configurations>

</application-control-service> 

Custom Log Service configuration

The Custom Event Service allows forwarding of Log Events to the business backbone. Therefore, it gathers events from certain internal topics and puts them onto a queue that automatically forwards them to the business backbone. Therefore the log level, the monitored bundles, the topic list and log queue name need to be configured. Furthermore the Custom Log Service supports the Maintenance Mode. In this mode it stops forwarding events to the configured log queue.

Note: Be careful with using the Custom Log Service, because a detailed logging operation can have strong performance and network usage impact!

The Custom Log Service can be configured as follows:

General format:

 <custom-log-service>

<maintenance mode="OFF">

<param name="LogToFile" value="FALSE"/>

<param name="LogFileLocation" value="c://tmp//maintenance.log"/>

</maintenance>

<!-- DEBUG, INFO, WARNING, ERROR -->

<threshold>ERROR</threshold>

<monitored-bundles>

<bundle>com.ibm.rcp.integrator.messagetofilemapper</bundle>

</monitored-bundles>

<!-- Monitored statuses: INSTALLED, STARTED, STOPPED -->

<monitored-status>

<status>INSTALLED</status>

</monitored-status>

<!-- Events sent to the following topics are captured. -->

<filter-topics>

<topic>com/ibm/integrator/businessevent/*</topic> 

</filter-topics>

<message> 

<microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

</message> 

Table 28 describes in detail the available Custom Log Service configuration parameters.

Table 28: Custom Log Service configuration properties

Property	Explanation
<custom-log-service	Tag which identifies the Custom Log Service configuration section in the XPDinteg.xml file.
	"ON" or "OFF" indicates Maintenance Mode on or off (see chapter ý6.6)
	"TRUE" or "FALSE" defines whether captured events during Maintenance Mode should be locally persisted to log file (specified unter LogFileLocation)
param name= "LogFileLocation" value=	String which contains the path and the name of the log file to which the received events are persisted during Maintenance Mode (if LogToFile=TRUE (e.g. "c://tmmaintenance.log")
	Log Level, determines how much log information is written possible values: {DEBUG | INFO | WARNING | ERROR}
	Contains a list of bundle names (separated by the tag) of which log events are monitored. When these bundles in this list reach the states specified under , the Custom Log Service needs to forward this information to the LogQ of the Monitoring System.
	String which contains the name of the monitored bundle. A single tag contains one monitored bundle.
	Contains a list of the monitored statuses, separated by the tag.
	A single tag contains one monitored status- Possible values: INSTALLED - The bundle has been installed STARTED - The bundle has been started RESOLVED - The bundle has been stopped When the bundles in the above list reach these specific states, the Custom Log Service needs to send this information to the LogQ of the Monitoring System.
	Contains a list of OSGi Event Admin Service event topics (separated by the tag) which the Custom Log Service is subscribed to. The Custom Log service will forward these events to the configured LogQ.
	A single tag contains one topic. Wildcards are allowed for the business event topics. Details are provided further below.
	micro broker JNDI Key used to connect to local micro broker for sending the log events to the local LogQ
	Local Queue JNDI key to forward the log events. This queue needs to be bridged to a business backbone queue (e.g. LogQ; refer to the section in the XPDinteg.xml file for its configuration).

The values for the tag are flexible because wildcards are supported. The following topic naming rules apply to the configuration:

Basic structure:

• com/ibm/integrator/SxpdApplStatusEvent/
• com/ibm/integrator/FlowStatus// {STARTED | FINISHED | FAILED}
• com/ibm/integrator/FlowStatus/// {INITIALIZED | EXECUTING | EXECUTED}
• com/ibm/integrator/businessevent//
  • describes the name of the monitored flow.
    The flow name is taken from the parameter of the tag in the flow definition file.
  • describes the state of the process transaction.

Possible values:

•  TRANSACTION_STARTED
•  TRANSACTION_FAILED (failure scenario)
•  TRANSACTION_COMPLETED (success scenario)
•  TRANSACTION_PROCESSING

The wildcard “*” can only be used at the end of a topic.

Listing 26 shows an example configuration for the Custom Log Service.

Listing 26: Custom Log Service sample configuration

 <custom-log-service>

<maintenance mode="OFF">

<param name="LogToFile" value="TRUE" | "FALSE"/>

<param name="LogFileLocation" value="c://tmp//maintenance.log"/>

</maintenance>

<threshold>ERROR</threshold>

<monitored-bundles>

<bundle>com.ibm.rcp.integrator.messagetofilemapper</bundle>

<bundle>com.ibm.rcp.integrator.transactionfilemapper</bundle> 

</monitored-bundles>

<monitored-status>

<status>INSTALLED</status>

</monitored-status>

<filter-topics>

<topic>com/ibm/integrator/XPDintegApplStatusEvent</topic>

<topic>com/ibm/integrator/businessevent/*</topic>

<topic>com/ibm/integrator/flowname</topic>

</filter-topics>

<message> 

<microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

<microbroker-logq-key>jms/XPDinteg_logQueue</microbroker-logq-key>

</message>

</custom-log-service> 

Custom Event Service configuration

The Custom Event Service allows forwarding of Business Events to the business (messaging) back-end. It gathers events from internal event with filtered event topics and puts them into the local event queue which automatically forwards these events to the Event Queue of the business back-end. Event topic filters can be configured to define the events which need to be forwarded.

The Custom Event Service also supports the Expeditor integrator Maintenance Mode during which event forwarding is stopped to avoid flooding the business back-end with events due to a planned maintenance outage (see chapter ‎6.6).

Note: Be careful with using the Custom Event Service, because a detailed event logging operation can have strong performance impact!

The Custom Event Service can be configured as follows (in Section_12 of the XPDinteg.xml).

General format:

 <custom-event-service maintenance-mode="OFF">

<maintenance mode="OFF">

<param name="LogToFile" value="FALSE"/>

<param name="LogFileLocation" value="c://tmp//maintenance.log"/>

</maintenance>

<filter-topics>

<topic>com/ibm/integrator/businessevent/*</topic> 

</filter-topics>

<message> 

<microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

<microbroker-eventq-key>jms/XPDinteg_eventQueue</microbroker-eventq-key>

</message>

</custom-event-service> 

Table 29 describes in detail the configuration parameters.

Table 29: Custom Event Service configuration properties

Property	Explanation
<custom-event-service	Tag which identifies the Custom Event Service configuration section in the XPDinteg.xml file.
	"ON" or "OFF" indicates Maintenance Mode on or off (see Maintenance Mode)
	"TRUE" or "FALSE" defines whether captured events during Maintenance Mode should be locally persisted to log file (specified unter LogFileLocation)
param name= "LogFileLocation" value=	String which contains the path and the name of the log file to which the received events are persisted during Maintenance Mode (if LogToFile=TRUE (e.g. "c:tmmaintenance.log")
	Contains a list of OSGi Event Admin Service event topics (separated by the tag) which the Custom Event Service is subscribed to. The Custom Event Service will forward these events to the configured EventQ.
	A single tag contains one topic. Wildcards are allowed for the business event topics. Details are provided further below.
	micro broker JNDI Key used to connect to local micro broker for sending the business events to the local EventQ.
	Local Event Queue JNDI key to forward the business events. This queue needs to be bridged to an event queue of the messaging back-end (e.g. EventQ; refer to the section in the XPDinteg.xml file for its configuration).

The values for the tag are flexible because wildcards are supported. The following topic naming rules apply to the configuration:

• Basic event structure: com/ibm/integrator/businessevent//
• describes the name of the monitored flow.
  The flow name is taken from the name parameter of the tag in the flow definition file.
• describes the state of the process transaction

Possible values:

• TRANSACTION_STARTED
• TRANSACTION_FAILED (failure scenario)
• TRANSACTION_COMPLETED (success scenario)
• TRANSACTION_PROCESSING

Note: The wildcard “*” can only be used at the end of a topic.

Listing 27 shows an example which configures the Custom Event Service to forward all com/ibm/integrator/businessevent/TRANSACTION_STARTED/FAILED/COMPLETED/PROCESSING events to the back-end queue configured under jms/XPDinteg_eventQueue.

Listing 27: Custom Event Service configuration example

 <custom-event-service>

<maintenance mode="OFF">

<param name="LogToFile" value="TRUE" | "FALSE"/>

<param name="LogFileLocation" value="c://tmp//maintenance.log"/>

</maintenance>

<filter-topics>

<topic>com/ibm/integrator/businessevent/*</topic> 

</filter-topics>

<message> 

<microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

<microbroker-eventq-key>jms/XPDinteg_eventQueue</microbroker-eventq-key>

</message>

</custom-event-service> 

Example:
The Custom Event Service should catch all TRANSACTION_FAILED events from the PutFtpFiles ACS flow. Listing 28 shows the PutFtpFile.flow definition file with


Listing 28: Default_PutFtpFiles.flow

 <?xml version="1.0" encoding="UTF-8"?>

<Process Name="PutFtpFile_Process" Trigger="com/ibm/integrator/flowtriggerevent/FileTransfer/FTP/FtpFile/dispatcher">

<XPDintegActivity 

Name="PutFtpFile_MessageToFile_FtpFile"

ActivityName="XPDINTEG_MESSAGE_TO_FILE"

JndiConnectionFactoryKey="jms/XPDinteg_ConnectionFactory" />

<XPDintegActivity 

Name="PutFtpFile_FileWriteToFTP_FtpFile"

ActivityName="XPDINTEG_FILE_WRITE_TO_FTP"

AdapterName="XPDINTEG_FTP_ADAPTER" />

</Process> 

If this flow fails, the following TRANSACTION_FAILED event will be published to the OSGi Event Admin Service:

 <topic>com/ibm/integrator/businessevent/PutFtpFile_Process/TRANSACTION_FAILED</topic> 

In order to capture this event type and forward it to the configured Event Queue of the back-end messaging system, the Custom Event Service configuration must contain this in its list:

 <topic>com/ibm/integrator/businessevent/PutFtpFile_Process/TRANSACTION_FAILED</topic> 

If all other transaction statuses should also be captured, the following wildcard option would be sufficient as in the Custom Event Service configuration:

 <topic>com/ibm/integrator/businessevent/PutFtpFile_Process/*</topic>